<html>
<head>
	<title>Marginalia for OJS Installation</title>
	<style type="text/css">
		ol li {
			margin: 1em 0 ;
		}
	</style>
</head>
<body>
<h1>Marginalia for OJS Installation</h1>

<p>The installation requires the following:</p>

<ul>
	<li>PHP 5 or later (4.3+ is probably still fine)</li>
	<li>OJS as of mid-September 2006 (a small fix was implemented to one of the
	page templates at this point)</li>
	<li>MySQL 4.1 or later (though a colleague has had success with MySQL 3; 
	I haven't tested with earlier versions or with Postgres)</li>
</ul>

<p>Back up your OJS database before performing the installation!  This applies
<em>particularly</em> to updates to Marginalia.  Marginalia does not change any
other OJS files or data, but upgrades can be harmful (see Upgrading, below).
If you're really paranoid - a good trait - back up your OJS files too.</p>

<p>Marginalia for OJS is a plugin.  Installing it is fairly straightforward.
First, copy the contents of the <kbd>ojs</kbd> directory in the installation
into your OJS directory.  Then you will need to log in to OJS as an administrator 
and switch on the plugin before it will work.  Note that only logged-in users 
can annotate articles in OJS.</p>

<p>Finally, you must create and populate the database tables required by Marginalia.  
The easiest way to do this is using OJS's built-in update procedure, as follows:</p>

<ol>
<li>Back up your OJS database in case something goes wrong.</li>
<li>Enable the Marginalia plugin (as described above) if you have not already done so.</li>
<li>From within your OJS install directory, run the following command:

<pre><code>php tools/upgrade.php upgrade</code></pre>
</li>
</ol>

<p>That's all there is to it.  If you run into any difficulties, let me know.</p>

<h3>Upgrades</h3>

<p>As of the December 2008 release of Marginalia for OJS the database schema
has changed.  If you upgrade to the new release, your existing annotation data
<em>will be</em> wiped out.  Unfortunately, I do not currently have an upgrade 
script to convert the old data to the new format.  I'm not sure this is a problem
as I'm not aware of installations that need to upgrade and keep their annotation
data.  If this is a problem for you, get in touch with me.  My email address is
displayed at <a href="http://www.geof.net/">www.geof.net</a>.</p>

<h2>Installation Problems</h2>

<p>If you have problems, it is probably because of a misconfiguration.  First, make sure
that you always connect to OJS using the canonical URL (see config.inc.php in your
OJS installation);  otherwise annotations may not
always appear.  If you are using a different url (e.g. <kbd>localhost</kbd>
instead of a numerical IP address), annotation will not work.</p>

<p>If your URL matches your configuration, I recommend installing and running the Firebug
extension for Firefox.  Among other things, it tracks AJAX requests from a web page to
the server.  The first thing to look for (other than any explicit errors reported by
Firebug) is the URL of the GET request sent to annotation/annotate.php with the parameter
"format=atom" when a page with annotations is first loaded.  Trying loading this URL
on its own in a browser window:  it should return an Atom feed containing the annotations
for that page.</p>

<h2>Uninstalling Annotation</h2>

<p>To uninstall annotation, simply delete the install directories:
<kbd>lib/marginalia</kbd> and <kbd>plugins/generic/MarginaliaPlugin</kbd>.  You
should also drop the database tables:  <kbd>annotations</kbd>, <kbd>preferences</kbd>,
and <kbd>keywords</kbd>.</p>

</body>
</html>

